GENERATE_WATERSHED and GENERATE_RIDGE_LINES

The GENERATE_WATERSHED command allows for the generation of a watershed, including stream flow and optionally watershed areas for each stream segment. The GENERATE_RIDGE_LINES command shares the same parameters, but finds ridge lines rather than stream lines. A ridge line is created wherever flow would accumulate in the inverse of the terrain surface. The following parameters are supported by the command.

  • FILENAME - filename of the layer(s) to process. If an empty value is passed in, all loaded terrain data will be used. This parameter can be listed more than once to specify multiple input files, like FILENAME="FILENAME_1" FILENAME="FILENAME_2".
  • STREAM_THRESHOLD - specifies the number of cells that have to drain to a particular location before that location is considered to be part of the stream/ridge network.
  • MAX_DEPTH - specifies the maximum depression depth (in meters) that will be filled prior to calculating the watershed. This is needed to prepare a terrain surface for flow analysis so that a continuous flow can be found. Note that while using a large MAX_DEPTH value may generate better results, it could also cause the process to take a lot longer.
  • GEN_AREAS - generate watershed area features for each found stream segment outlining the area that drains into that stream. Enabled by default for watersheds and disabled for ridge lines, use GEN_AREAS=NO to disable.
  • SMOOTH_STREAMS - specifies whether or not generated streams/ridge lines should have smoothing applied to improve appearance. This option is enabled by default. Use SMOOTH_STREAMS=NO to disable smoothing.
  • FLOW_TO_POS - specifies the X and Y location (or longitude/latitude) of a position to generate an area with all parts of the terrain surface that flow to (or near) that point in the vector area feature. The format is FLOW_TO_POS="x,y". You can provide multiple FLOW_TO_POS parameters to find the flow to multiple locations. Use FLOW_TO_POS_THRESH to specify how close to the position the flow has to go in order to consider the source point part of that area. Use FLOW_TO_POS_PROJ to specify the projection of the position. If that is not provided it will be assumed to be in the current projection.
  • FLOW_TO_POS_THRESH - specifies how many samples away from the sample containing the specified FLOW_TO_POS that the flow can be and still be considered to go to that point. The default is FLOW_TO_POS_THRESH=1.
  • FLOW_TO_POS_PROJ - special Projection Specification parameter providing the projection of the FLOW_TO_POS.
  • FILLED_DEM_FILENAME - specifies the full path and name of a GMG (Global Mapper Grid) file to save the depression filled DEM to after finding it. The default is to not save the filled DEM to a GMG file.
  • GEN_FLOW_DIR_POINTS - specifies whether or not a separate layer containing a point feature with the flow direction and accumulation at each sample location. Add GEN_FLOW_DIR_POINTS=YES to create the layer. The symbol can be set with the FLOW_DIR_SYMBOL parameter.
  • FLOW_DIR_SYMBOL - specifies the name of the point symbol to use for the flow direction points. The specified symbol will be rotated to show the flow direction. The default is the medium black arrow.
  • SHOW_FLOW_ACCUM - specifies whether or not the flow accumulation grid should be saved as a new layer. Use SHOW_FLOW_ACCUM=YES to enable saving the flow accumulation to a new grid layer.
  • CALC_STRAHLER - specifies whether or not the Strahler stream order attribute should be calculated for the stream lines. Use CALC_STRAHLER=YES to enable. Use only for GENERATE_WATERSHED command.
  • Obstructions from Vector Data:

    • USE_VECTOR_HEIGHTS - indicates whether or not loaded vector data with elevation values should be considered when performing the watershed analysis. This allows you to use things like buildings, culverts, dams, etc. to block or modify the flow, creating a more realistic watershed. The default is to not use vector data. Use USE_VECTOR_HEIGHTS="YES" to specify that you want to use heights from vector data.

    • VECTOR_FILENAME - specifies the filename/description of the vector layer(s) to get obstructions from. If not provided, all loaded vector layers will be considered. You can provide multiple VECTOR_FILENAME parameters to explicitly specify multiple layers.

    • VECTOR_AREAS_HIDDEN - specifies that any locations within an obstruction area, or immediately adjacent to an obstruction line, will not allow flow into the region from outside, regardless of the height of the feature. The default is "NO".

    • VECTOR_ONLY_3D - specifies that only vector features with elevations will be considered as obstructions. By default, 2D features will also be used as obstructions. Any 2D features that are used will act as no-flow obstructions, so flow cannot enter them regardless of the VECTOR_AREAS_HIDDEN value.

    • VECTOR_HEIGHTS_ABOVE_SEA_LEVEL - specifies whether the elevation values stored with vector features are relative to the ground or relative to mean sea level. Typically heights for vector features are specified relative to the ground. If any area features are included and their heights are relative to the ground, the obstruction heights within those areas will be increased by the specified amount. Any features that have an explicit altitude mode set for the feature or layer will obey that over this settings. The default is "NO" (heights are relative to the ground). To specify that vector heights should be relative to sea level, use VECTOR_HEIGHTS_ABOVE_SEA_LEVEL="YES"

  • SPATIAL_RES - specifies spacing of grid points used to calculate the watershed. A smaller grid spacing results in higher fidelity, but the calculation process will take longer. Typically you'll want to use the default value which is the minimum spatial resolution of all loaded data. Should be formatted as x_resolution,y_resolution. The units are the units of the current global projection. For example, if UTM was the current global projection and you wanted to use a grid with a 30 meter spacing, the parameter/value pair would look like SPATIAL_RES=30.0,30.0.
  • SPATIAL_RES_METERS - specifies spatial resolution to use in meters. The value in meters will automatically be converted to the current view/export projection units. For example, to do an export at 2.0 meter spacing (or as close as you can get to that in the current units), use SPATIAL_RES_METERS=2.0, or to do an export at 1.0 meters in X by 1.5 meters in Y, use SPATIAL_RES_METERS="1.0,1.5".
  • SAMPLING_METHOD - specifies the sampling method to use when sampling the terrain layers involved in the watershed calculation. The following values are supported:
    • DEFAULT - Use either automatic resampling based on export or layer resampling, depending on setting of global flag about whether to resample on export
    • AUTO - Automatically select a resampling method based on how the export resolution and bounds compare to the original layout for a layer. For example if you export to a lower resolution a box averager of appropriate size may be used automatically
    • LAYER - Use the sampling method set for each layer
    • The list of SAMPLING_METHOD values for the IMPORT command can also be specified to use a particular sampling method for all layers being exported/
      • NEAREST_NEIGHBOR - use the nearest neighbor sampling method
      • BILINEAR - use bilinear interpolation
      • BICUBIC - use bicubic interpolation
      • BOX_2X2 - use a 2x2 box average
      • BOX_3X3 - use a 3x3 box average
      • BOX_4X4 - use a 4x4 box average
      • BOX_5X5 - use a 5x5 box average
      • BOX_6X6 - use a 6x6 box average
      • BOX_7X7 - use a 7x7 box average
      • BOX_8X8 - use a 8x8 box average
      • BOX_9X9 - use a 9x9 box average
      • MAX_2X2 - use maximum value found in 2x2 box (for image layers, use brightest color)
      • MAX_3X3 - use maximum value found in 3x3 box (for image layers, use brightest color)
      • MAX_4X4 - use maximum value found in 4x4 box (for image layers, use brightest color)
      • MAX_5X5 - use maximum value found in 5x5 box (for image layers, use brightest color)
      • MAX_6X6 - use maximum value found in 6x6 box (for image layers, use brightest color)
      • MAX_7X7 - use maximum value found in 7x7 box (for image layers, use brightest color)
      • MAX_8X8 - use maximum value found in 8x8 box (for image layers, use brightest color)
      • MAX_9X9 - use maximum value found in 9x9 box(for image layers, use brightest color)
      • MED_2X2 - use median value found in 2x2 box
      • MED_3X3 - use median value found in 3x3 box
      • MED_4X4 - use median value found in 4x4 box
      • MED_5X5 - use median value found in 5x5 box
      • MED_6X6 - use median value found in 6x6 box
      • MED_7X7 - use median value found in 7x7 box
      • MED_8X8 - use median value found in 8x8 box
      • MED_9X9 - use median value found in 9x9 box
      • MIN_2X2 - use minimum value found in 2x2 box (for image layers, use darkest color)
      • MIN_3X3 - use minimum value found in 3x3 box (for image layers, use darkest color)
      • MIN_4X4 - use minimum value found in 4x4 box (for image layers, use darkest color)
      • MIN_5X5 - use minimum value found in 5x5 box (for image layers, use darkest color)
      • MIN_6X6 - use minimum value found in 6x6 box (for image layers, use darkest color)
      • MIN_7X7 - use minimum value found in 7x7 box (for image layers, use darkest color)
      • MIN_8X8 - use minimum value found in 8x8 box (for image layers, use darkest color)
      • MIN_9X9 - use minimum value found in 9x9 box (for image layers, use darkest color)
      • BLUR_3X3 - perform a Gaussian Blur using 3x3 kernel
      • BLUR_5X5 - perform a Gaussian Blur using 5x5 kernel
      • BLUR_7X7 - perform a Gaussian Blur using 7x7 kernel
  • FILL_GAPS - specifies that small gaps in between and within the data sets being used to generate the watershed will be filled in by interpolating the surrounding data to come up with an elevation for the point in question. This option is on by default, specify FILL_GAPS=NO to turn off.
  • LAYER_DESC - specifies the name to assign to this layer. If no layer description is provided, the default name of "GENERATED WATERSHED" will be used.
  • MIN_STREAM_LEN - specifies the minimum length in meters of a stream segment at the start of a stream network. Any streams shorter than this that have nothing flowing into them will be discarded. The default is to keep all streams regardless of length.
  • KEEP_ZERO_AT_ZERO - specifies whether or not to modify 0 (typically ocean) values to allow flow to continue across expanses of 0 elevation. The default is to enable this so 0 values don't change. If you want to model flow across 0 surfaces, add KEEP_ZERO_AT_ZERO=NO.
  • MIN_ELEV - If specified, ridge lines will only be found where the elevation is greater than or equal to the MIN_ELEV value. For use with GENERATE_RIDGELINES command only.

  • See also Specify Bounds for Operation

    • GLOBAL_BOUNDS - specifies the combine bounds in units of the current global projection. There should be 4 values in a comma-delimited list following the parameter name. The values should be in order of minimum x, minimum y, maximum x, maximum y.
    • GLOBAL_BOUNDS_SIZE - specifies the combine bounds in units of the current global projection. There should be 4 values in a comma-delimited list following the parameter name. The values should be in order of minimum x, minimum y, width in x, width in y.
    • LAT_LON_BOUNDS - specifies the combine bounds in latitude/longitude degrees. There should be 4 values in a comma-delimited list following the parameter name. The values should be in order of west-most longitude, southern-most latitude, eastern-most longitude, northern-most latitude.
    • LAYER_BOUNDS - specifies that the operation should use the bounds of the loaded layer(s) with the given filename. For example, to export to the bounds of the file "c:\test.tif", you would use LAYER_BOUNDS="c:\test.tif". Keep in mind that the file must be currently loaded.
    • LAYER_BOUNDS_EXPAND - specifies that the operation should expand the used LAYER_BOUNDS bounding box by some amount. The amount to expand the bounding rectangle by should be specified in the current global projection. For example, if you have a UTM/meters projection active and want to expand the bounds retrieved from the LAYER_BOUNDS parameter by 100 meters on the left and right, and 50 meters on the top and bottom, you could use LAYER_BOUNDS_EXPAND="100.0,50.0". You can also specify a single value to apply to all 4 sides, or supply 4 separate values in the order left,top,right,bottom.
    • SNAP_BOUNDS_TO_MULTIPLE - specifies that the top-left corner of the bounding box for the operation should be snapped to a multiple of the given value. For example, using SNAP_BOUNDS_TO_MULTIPLE=1 will snap the top-left corner to the nearest whole number. The values will always go smaller for X/easting/longitude and larger to Y/northing/latitude so you always get at least what is requested.
    • SNAP_BOUNDS_TO_SPACING - specifies that the top-left corner of the bounding box for the operation should be snapped to a multiple of the resolution of the operation. For example, if you are exporting at 5 meter spacing, the top left corner will be snapped to the nearest multiple of 5. Use SNAP_BOUNDS_TO_SPACING=YES to enable or SNAP_BOUNDS_TO_SPACING=NO to disable. If not provided, the global setting for snapping exports to the nearest sample spacing boundary from the Advanced section of the General tab of the Configuration dialog will be used.
    • USE_EXACT_BOUNDS - specifies that the exact bounds that were defined in the command should be used. Generally, when the bounds specified in a command are not the same as the data bounds, the command uses the intersection between the two. When USE_EXACT_BOUNDS=YES is specified, the command will use the bounds as specified, instead of the intersection.

  • See also Cropping Operations to Polygons/Areas

    • POLYGON_CROP_FILE - specifies the full path and filename or loaded layer description of a vector file/loaded layer containing one or more polygon features to which the operation should be cropped. If multiple polygons are found in the specified file the polygon which has the largest intersection with the data to be combined will be used as the crop polygon (see POLYGON_CROP_USE_ALL or POLYGON_CROP_USE_EACH for exceptions).
    • POLYGON_CROP_FILE_PROJ - specifies the projection to use for the POLYGON_CROP_FILE. Use if the file doesn't have an associated projection file. See special Projection Specification for instructions.
    • POLYGON_CROP_NAME - specifies the name of a polygon shape previously defined using the DEFINE_SHAPE command to which the export should be cropped. The coordinates in the shape need to have been provided in whatever projection the new terrain layer will be in (i.e. the current projection). If you want to crop to any area features that are selected with the Digitizer Tool in the user interface rather than a defined polygon, use POLYGON_CROP_NAME="SELECTED".
    • POLYGON_CROP_USE_ALL - specifies that if a POLYGON_CROP_FILE is specified that contains multiple polygons, the operation will be cropped to all polygons in that file rather than just the best-fit polygon.
    • POLYGON_CROP_USE_EACH - specifies that if a POLYGON_CROP_FILE is specified that contains multiple polygons, the operation will generate a separate export for each polygons in that file rather than just the best-fit polygon. See the POLYGON_CROP_BBOX_ONLY and POLYGON_CROP_NAME_ATTR options for naming and other options when using this parameter. Use POLYGON_CROP_USE_EACH=YES to enable. This parameter also works with FEATHER_BLEND_EDGES. Use POLYGON_CROP_USE_EACH=YES with FEATHER_BLEND_POLY_FILE or FEATHER_BLEND_POLY to feather the edges of multiple polygons.
    • POLYGON_CROP_EXCLUDE - specifies that the crop areas are actually regions to exclude from the export rather than include. If you add POLYGON_CROP_EXCLUDE=YES to the command the results will contain everything outside the crop areas but within the full export bounds.
    • POLYGON_CROP_COMBINE_DUPS - specifies that if a POLYGON_CROP_FILE is specified that contains multiple polygons and POLYGON_CROP_USE_EACH is set, whether or not polygons with duplicate values for the attribute used for filenaming will be combined into a single export or split into separate exports. The default is POLYGON_CROP_COMBINE_DUPS=YES.
    • POLYGON_CROP_BBOX_ONLY - specifies that if the POLYGON_CROP_USE_EACH parameter is specified that each export should just be cropped to the bounding box of each polygon rather than the actual boundary of the polygon. Use POLYGON_CROP_BBOX_ONLY=YES to enable only cropping to the bounding box.
    • POLYGON_CROP_GRID_ONLY - specifies that any crop polygon(s) are used only to determine which tile/grid cells will be exported. For each tile/grid cell that intersects a crop polygon, the full tile/grid cell will be exported. Use POLYGON_CROP_GRID_ONLY=YES to enable.
    • POLYGON_CROP_INT_DATA_BOUNDS - control how the bounding box for the export is determined if a crop polygon is specified. If this option is disabled, the export bounds will be the bounds of the crop area(s), even if they extend outside the data bounds, unless you explicitly specified a bounding box in the other parameters (i.e. LAYER_BOUNDS, GLOBAL_BOUNDS, etc.). If the option is enabled, the export bounds will be the intersection of the crop area bounds and the non-cropped bounding box (i.e. full data bounds or specified bounds in other parameter). This parameter is enabled by default, use POLYGON_CROP_INT_DATA_BOUNDS=NO to disable.
    • POLYGON_CROP_NAME_ATTR - used to control the filenames generated when cropping to multiple polygons using the POLYGON_CROP_USE_EACH parameter. See special Attribute Name parameter details. This value will be appended to any filename specified in the EXPORT FILENAME parameter. If no value is provided, the exported files will be sequentially numbered.
    • POLYGON_CROP_FOLDER_ATTR - used to control the filenames generated when cropping to multiple polygons using the POLYGON_CROP_USE_EACH parameter. See special Attribute Name parameter details.
    • POLYGON_CROP_FILENAME_SUFFIX - specifies the text to insert in the output filename just before the file extension when cropping to polygons. For example, if you add POLYGON_CROP_FILENAME_SUFFIX="_out", the original FILENAME was "my_file_.dem" and the value from the polygon was "A1", you would get an output filename of "my_file_A1_out.dem".
    • POLYGON_CROP_COMPARE_STR - specifies a compare string to use to filter out the areas in the polygon crop file. See the COMPARE_STR parameter for the EDIT_VECTOR script command for details.